#![doc(html_no_source)]
//! # log4r - 企业级 Rust 日志库
//!
//! 基于 tracing 生态开发，提供 FATAL 级别系统日志集成。
//!
//! ## 特性
//!
//! - 6 级日志：TRACE, DEBUG, INFO, WARN, ERROR, FATAL
//! - FATAL 级别自动写入系统日志（Windows Event Log / systemd journal / os_log）
//! - TOML 配置文件支持
//! - 异步日志处理
//! - 零配置快速启动
//!
//! ## 快速开始
//!
//! ```rust,ignore
//! use log4r::init;
//!
//! fn main() {
//!     init().expect("初始化日志失败");
//!     tracing::info!("Hello, log4r!");
//! }
//! ```

#![deny(warnings)]
#![deny(clippy::unwrap_used, clippy::expect_used)]

// 公共模块 - 用户可直接访问
pub mod appender;
pub mod config;
pub mod error;
pub mod event;
pub mod filter;
pub mod formatter;
pub mod layer;
pub mod level;
pub mod macros;

// 异步运行时模块
pub mod async_rt;

// 公共导出
pub use appender::{Appender, ConsoleAppender, ConsoleTarget};
pub use config::types::RotationPeriod;
pub use error::Log4rError;
pub use event::LogEvent;
#[cfg(feature = "color")]
pub use formatter::{cached_terminal_color_support, should_colorize, ColoredFormatter};
pub use formatter::{Formatter, TextFormatter};
pub use level::{Level, ParseLevelError};

use std::path::Path;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
use std::time::Duration;

use async_rt::{LogChannel, Worker, WorkerConfig};
use crossbeam_channel::Sender;
use layer::Log4rLayer;
use tracing_subscriber::prelude::*;

// 全局初始化状态
static INITIALIZED: AtomicBool = AtomicBool::new(false);

// 内部错误计数器（用于限流）
static INTERNAL_ERROR_COUNT: AtomicU64 = AtomicU64::new(0);

/// 记录内部错误到 stderr（带限流）
///
/// 每 1000 次错误只输出一次，避免刷屏。
/// 此函数用于日志系统内部错误的报告，不会 panic。
///
/// # Arguments
///
/// * `message` - 错误消息
///
/// # 示例
///
/// ```rust,ignore
/// log_internal_error("Appender 写入失败: 文件已满");
/// ```
pub(crate) fn log_internal_error(message: &str) {
    let count = INTERNAL_ERROR_COUNT.fetch_add(1, Ordering::Relaxed);

    // 每 1000 次错误输出一次（第 0, 1000, 2000... 次）
    if count % 1000 == 0 {
        eprintln!("[log4r] 内部错误 (第 {} 次): {}", count + 1, message);
    }
}

// 标记是否已调用 shutdown，防止重复 flush
static SHUTDOWN_CALLED: AtomicBool = AtomicBool::new(false);

// 标记 panic hook 是否已注册
static PANIC_HOOK_REGISTERED: AtomicBool = AtomicBool::new(false);

// 全局日志器状态容器
static LOGGER: OnceLock<Mutex<GlobalLogger>> = OnceLock::new();

/// 注册 panic hook，在 panic 时自动 flush 日志
///
/// 此函数在 init 时调用，确保 panic 场景下日志不丢失。
/// 使用链式调用保留原有 panic hook。
///
/// # 行为
///
/// - 如果已注册，跳过
/// - 保存原有 panic hook
/// - 设置新 hook：先 flush 日志，再调用原有 hook
/// - panic 场景使用较短超时（1 秒）以快速退出
fn register_panic_hook() {
    // 检查是否已注册（防止重复注册）
    if PANIC_HOOK_REGISTERED.swap(true, Ordering::SeqCst) {
        return;
    }

    // 保存原有 panic hook
    let original_hook = std::panic::take_hook();

    // 设置新的 panic hook
    std::panic::set_hook(Box::new(move |panic_info| {
        // 检查是否已调用过 shutdown
        if !SHUTDOWN_CALLED.swap(true, Ordering::SeqCst) {
            // 尝试 flush 日志（静默处理错误）
            if let Some(logger_mutex) = LOGGER.get() {
                if let Ok(mut logger) = logger_mutex.lock() {
                    // 取出 Worker 并关闭（使用较短超时）
                    if let Some(worker) = logger.worker.take() {
                        // panic 场景使用 1 秒超时，快速退出
                        let _ = worker.shutdown_with_timeout(Duration::from_secs(1));
                    }
                }
            }
        }

        // 调用原有的 panic hook
        original_hook(panic_info);
    }));
}

/// 全局日志器状态
///
/// 实现 `Drop` trait，在进程正常退出时自动 flush 日志。
/// 如果用户已显式调用 `shutdown()`，Drop 不会重复执行 flush。
struct GlobalLogger {
    /// 配置
    #[allow(dead_code)]
    config: config::Log4rConfig,
    /// Appender 列表
    appenders: Vec<Arc<dyn Appender>>,
    /// 异步工作线程
    worker: Option<Worker>,
    /// 日志通道发送端
    #[allow(dead_code)]
    sender: Option<Sender<LogEvent>>,
    /// Fallback Appender（stderr）
    #[allow(dead_code)]
    fallback: ConsoleAppender,
}

impl Drop for GlobalLogger {
    /// 进程退出时自动 flush 日志
    ///
    /// 在 GlobalLogger 被销毁时（通常是进程正常退出），
    /// 自动调用 shutdown 逻辑，确保所有日志写入完成。
    ///
    /// # 行为
    ///
    /// - 如果已调用 `shutdown()`（SHUTDOWN_CALLED 为 true），跳过
    /// - 否则，尝试关闭 Worker（超时 5 秒）
    /// - 然后 flush 和 close 所有 Appender
    /// - 所有错误静默处理，不影响进程退出
    fn drop(&mut self) {
        // 检查是否已经调用过 shutdown
        if SHUTDOWN_CALLED.load(Ordering::SeqCst) {
            return;
        }

        // 标记正在执行 shutdown，防止重复
        SHUTDOWN_CALLED.store(true, Ordering::SeqCst);

        // 尝试关闭 Worker（静默处理错误）
        if let Some(worker) = self.worker.take() {
            let _ = worker.shutdown_with_timeout(Duration::from_secs(5));
        }

        // 尝试 flush 和 close 所有 Appender（静默处理错误）
        for appender in &self.appenders {
            let _ = appender.flush();
            let _ = appender.close();
        }
    }
}

/// 使用默认配置快速初始化
///
/// 默认配置：
/// - 级别：INFO
/// - 输出：stdout 控制台
/// - 格式：默认文本格式
/// - 异步：启用（queue_size = 10000）
///
/// # Errors
///
/// - `AlreadyInitialized` - 日志系统已初始化
///
/// # Examples
///
/// ```rust,ignore
/// log4r::init()?;
/// tracing::info!("Hello, log4r!");
/// ```
pub fn init() -> Result<(), Log4rError> {
    // 检查是否已初始化
    if INITIALIZED.swap(true, Ordering::SeqCst) {
        return Err(Log4rError::AlreadyInitialized);
    }

    // 创建默认配置
    let config = config::Log4rConfig::default();

    // 调用 init_with_config
    init_with_config(config)
}

/// 从配置文件初始化日志系统
///
/// 从指定的 TOML 配置文件加载配置并初始化日志系统。
/// 支持相对路径和绝对路径，配置文件格式参见 [`config`] 模块文档。
///
/// # Arguments
///
/// * `path` - 配置文件路径，支持以下类型：
///   - `&str` - 字符串切片，如 `"log4r.toml"`
///   - `String` - 字符串
///   - `&Path` - 路径引用
///   - `PathBuf` - 路径缓冲区
///
/// # Errors
///
/// - [`Log4rError::IoError`] - 文件不存在或无法读取
/// - [`Log4rError::ConfigError`] - 配置解析失败，错误信息包含位置和具体问题
/// - [`Log4rError::AlreadyInitialized`] - 日志系统已初始化
///
/// # Examples
///
/// 基本用法：
///
/// ```rust,ignore
/// // 从当前目录加载配置
/// log4r::init_from_file("log4r.toml")?;
/// tracing::info!("日志系统已从配置文件初始化");
/// ```
///
/// 使用绝对路径：
///
/// ```rust,ignore
/// use std::path::PathBuf;
///
/// let config_path = PathBuf::from("/etc/myapp/log4r.toml");
/// log4r::init_from_file(&config_path)?;
/// ```
///
/// 错误处理：
///
/// ```rust,ignore
/// match log4r::init_from_file("log4r.toml") {
///     Ok(()) => println!("初始化成功"),
///     Err(log4r::Log4rError::IoError(e)) => {
///         eprintln!("配置文件读取失败: {}", e);
///     }
///     Err(log4r::Log4rError::ConfigError(msg)) => {
///         eprintln!("配置解析失败: {}", msg);
///     }
///     Err(log4r::Log4rError::AlreadyInitialized) => {
///         eprintln!("日志系统已初始化");
///     }
///     Err(e) => eprintln!("其他错误: {}", e),
/// }
/// ```
pub fn init_from_file(path: impl AsRef<Path>) -> Result<(), Log4rError> {
    // 1. 检查是否已初始化
    if INITIALIZED.swap(true, Ordering::SeqCst) {
        return Err(Log4rError::AlreadyInitialized);
    }

    // 2. 调用 config::load_config() 加载配置文件
    //    load_config 内部处理文件读取和 TOML 解析，错误信息包含行号
    let config = match config::load_config(path.as_ref()) {
        Ok(cfg) => cfg,
        Err(e) => {
            // 重置 INITIALIZED 标志，允许用户修正后重试
            INITIALIZED.store(false, Ordering::SeqCst);
            return Err(e);
        }
    };

    // 3. 调用 init_with_config() 完成初始化
    match init_with_config(config) {
        Ok(()) => Ok(()),
        Err(e) => {
            // 重置 INITIALIZED 标志，允许用户修正后重试
            INITIALIZED.store(false, Ordering::SeqCst);
            Err(e)
        }
    }
}

/// 使用指定配置初始化（内部函数）
///
/// # Arguments
///
/// * `config` - 日志配置
///
/// # Errors
///
/// - `ConfigError` - 配置无效或 tracing subscriber 设置失败
pub(crate) fn init_with_config(config: config::Log4rConfig) -> Result<(), Log4rError> {
    // 验证异步配置
    config.async_config.validate()?;

    // 1. 根据配置创建 Appender 列表
    let mut appenders: Vec<Arc<dyn Appender>> = Vec::new();

    // 创建控制台 Appender（如果配置了或使用默认）
    if let Some(ref console_config) = config.appenders.console {
        if console_config.enabled {
            let target = match console_config.target {
                config::ConsoleTarget::Stdout => ConsoleTarget::Stdout,
                config::ConsoleTarget::Stderr => ConsoleTarget::Stderr,
            };
            let level = console_config.level.unwrap_or(config.level);

            // 根据配置启用彩色输出
            #[cfg(feature = "color")]
            let console = {
                let c = ConsoleAppender::with_target(target).with_level(level);
                if console_config.colored {
                    c.with_colored()
                } else {
                    c
                }
            };

            #[cfg(not(feature = "color"))]
            let console = ConsoleAppender::with_target(target).with_level(level);

            appenders.push(Arc::new(console));
        }
    } else {
        // 默认：stdout 控制台
        let console = ConsoleAppender::new().with_level(config.level);
        appenders.push(Arc::new(console));
    }

    // 创建文件 Appender（如果配置了）
    // 根据 max_size 和 rotation 配置选择 RotatingFileAppender 或 FileAppender
    if let Some(ref file_config) = config.appenders.file {
        if file_config.enabled {
            let level = file_config.level.unwrap_or(config.level);

            // 解析 max_size（如果配置了）
            let max_size = file_config
                .max_size
                .as_ref()
                .map(|s| config::parse_size(s))
                .transpose()?;

            // 获取时间轮转周期
            let rotation_period = file_config.rotation.unwrap_or(RotationPeriod::None);

            // 如果启用了大小轮转或时间轮转，使用 RotatingFileAppender
            if max_size.is_some() || rotation_period != RotationPeriod::None {
                let rotating_appender = appender::RotatingFileAppender::with_full_config(
                    &file_config.path,
                    max_size,
                    rotation_period,
                    file_config.max_files,
                )?
                .with_level(level);
                appenders.push(Arc::new(rotating_appender));
            } else {
                // 使用普通 FileAppender
                let file_appender =
                    appender::FileAppender::new(&file_config.path)?.with_level(level);
                appenders.push(Arc::new(file_appender));
            }
        }
    }

    // 2. 创建异步通道和 Worker
    let channel = LogChannel::new(config.async_config.queue_size);
    let sender = channel.sender();
    let receiver = channel.receiver().clone();

    // 3. 创建 fallback Appender（stderr）并启动 Worker
    let fallback: Arc<dyn Appender> = Arc::new(ConsoleAppender::with_target(ConsoleTarget::Stderr));
    let app_name = config.app_name.clone();
    // AC-14.4.5 #9: 从 AsyncConfig 构建 WorkerConfig
    let worker_config = WorkerConfig {
        batch_size: config.async_config.batch_size,
        batch_timeout_ms: config.async_config.batch_timeout_ms,
    };
    let worker = Worker::start(
        receiver,
        appenders.clone(),
        fallback,
        worker_config,
        app_name,
    );

    // 4. 创建 Log4rLayer 并注册到 tracing
    let layer = Log4rLayer::new(sender.clone(), config.level);

    let subscriber = tracing_subscriber::registry().with(layer);

    tracing::subscriber::set_global_default(subscriber)
        .map_err(|e| Log4rError::ConfigError(format!("设置 subscriber 失败: {}", e)))?;

    // 5. 注册 panic hook（用于自动 flush）
    register_panic_hook();

    // 6. 存储 GlobalLogger
    let logger = GlobalLogger {
        config,
        appenders,
        worker: Some(worker),
        sender: Some(sender),
        fallback: ConsoleAppender::with_target(ConsoleTarget::Stderr),
    };

    LOGGER
        .set(Mutex::new(logger))
        .map_err(|_| Log4rError::AlreadyInitialized)?;

    Ok(())
}

/// 创建 Builder 进行程序化配置
///
/// # Examples
///
/// ```rust,ignore
/// log4r::builder()
///     .with_level(Level::DEBUG)
///     .with_console(ConsoleTarget::Stdout)
///     .with_file("logs/app.log")
///     .init()?;
/// ```
pub fn builder() -> Log4rBuilder {
    Log4rBuilder::new()
}

/// 安全关闭日志系统
///
/// 等待所有待写入日志完成，然后关闭所有 Appender。
/// 默认超时时间为 5 秒。如需自定义超时时间，请使用 [`shutdown_timeout`]。
///
/// # 关闭流程
///
/// 1. 停止接收新日志
/// 2. 等待队列中所有日志写入完成
/// 3. flush 所有 Appender
/// 4. close 所有 Appender
///
/// # Errors
///
/// - [`Log4rError::NotInitialized`] - 日志系统未初始化
/// - [`Log4rError::ShutdownTimeout`] - 关闭超时（5 秒内未完成）
///
/// # Examples
///
/// ```rust,ignore
/// // 初始化日志系统
/// log4r::init()?;
///
/// // 记录日志
/// tracing::info!("应用程序运行中...");
///
/// // 安全关闭，确保所有日志写入完成
/// log4r::shutdown()?;
/// ```
///
/// # 注意
///
/// - shutdown 完成后，`is_initialized()` 仍返回 `true`（MVP 不支持重新初始化）
/// - 重复调用 shutdown 是安全的，会返回 `Ok(())`
pub fn shutdown() -> Result<(), Log4rError> {
    shutdown_timeout(Duration::from_secs(5))
}

/// 带超时的安全关闭日志系统
///
/// 等待所有待写入日志完成，然后关闭所有 Appender。
/// 如果在指定时间内未能完成，返回 `ShutdownTimeout` 错误。
///
/// # 关闭流程
///
/// 1. 检查日志系统是否已初始化
/// 2. 获取全局 Logger 锁
/// 3. 发送关闭信号给 Worker
/// 4. 等待队列中所有日志写入完成
/// 5. flush 并 close 所有 Appender
///
/// # Arguments
///
/// * `timeout` - 最大等待时间
///
/// # Errors
///
/// - [`Log4rError::NotInitialized`] - 日志系统未初始化
/// - [`Log4rError::ShutdownTimeout`] - 关闭超时，包含超时秒数
///
/// # Examples
///
/// ```rust,ignore
/// use std::time::Duration;
///
/// // 使用 10 秒超时
/// log4r::shutdown_timeout(Duration::from_secs(10))?;
/// ```
///
/// # 注意
///
/// - shutdown 完成后，`is_initialized()` 仍返回 `true`（MVP 不支持重新初始化）
/// - 如果 Worker 已被关闭（重复调用 shutdown），此函数返回 `Ok(())`
pub fn shutdown_timeout(timeout: Duration) -> Result<(), Log4rError> {
    // 检查是否已初始化
    if !INITIALIZED.load(Ordering::SeqCst) {
        return Err(Log4rError::NotInitialized);
    }

    // 检查是否已调用过 shutdown（防止重复调用）
    if SHUTDOWN_CALLED.swap(true, Ordering::SeqCst) {
        // 已经调用过 shutdown，直接返回成功
        return Ok(());
    }

    // 获取全局 logger 并关闭 worker
    if let Some(logger_mutex) = LOGGER.get() {
        let mut logger = logger_mutex.lock().map_err(|_| Log4rError::AppenderError {
            name: "GlobalLogger".to_string(),
            cause: "获取全局日志器锁失败（Mutex poisoned）".to_string(),
        })?;

        // 取出 worker 并关闭
        if let Some(worker) = logger.worker.take() {
            worker
                .shutdown_with_timeout(timeout)
                .map_err(|_| Log4rError::ShutdownTimeout(timeout.as_secs()))?;
        }
    }

    // 注意：不重置 INITIALIZED，MVP 不支持重新初始化

    Ok(())
}

/// 检查日志系统是否已初始化
pub fn is_initialized() -> bool {
    INITIALIZED.load(Ordering::SeqCst)
}

/// Builder 模式配置构建器
///
/// 提供链式调用 API 进行程序化配置日志系统。支持配置日志级别、
/// 输出目标（控制台/文件）、异步模式等选项。
///
/// # 默认值
///
/// | 选项 | 默认值 |
/// |------|--------|
/// | 级别 | INFO |
/// | 控制台 | stdout |
/// | 文件 | 无 |
/// | 异步 | 启用 |
/// | 队列大小 | 10000 |
///
/// # Examples
///
/// 使用默认配置：
///
/// ```rust,ignore
/// log4r::builder().init()?;
/// ```
///
/// 自定义配置：
///
/// ```rust,ignore
/// use log4r::{builder, Level, ConsoleTarget};
///
/// builder()
///     .with_level(Level::Debug)
///     .with_app_name("my-app")
///     .with_console(ConsoleTarget::Stdout)
///     .with_file("logs/app.log")
///     .with_async(true)
///     .with_queue_size(5000)
///     .init()?;
/// ```
///
/// # 错误处理
///
/// `init()` 方法返回 `Result<(), Log4rError>`，可能的错误：
/// - `AlreadyInitialized` - 日志系统已初始化
/// - `ConfigError` - 配置无效
#[derive(Debug, Clone)]
pub struct Log4rBuilder {
    /// 全局日志级别
    level: Level,
    /// 应用名称
    app_name: Option<String>,
    /// 控制台目标
    console_target: Option<ConsoleTarget>,
    /// 文件路径
    file_path: Option<std::path::PathBuf>,
    /// 文件轮转大小（字节），None 表示不启用轮转
    rotation_size: Option<u64>,
    /// 时间轮转周期
    rotation_period: RotationPeriod,
    /// 历史文件数量限制
    max_files: Option<u32>,
    /// 异步模式
    async_enabled: bool,
    /// 队列大小
    queue_size: usize,
    /// 批量处理大小
    batch_size: usize,
    /// 批量超时时间（毫秒）
    batch_timeout_ms: u64,
    /// 彩色输出（需要 color feature）
    #[cfg(feature = "color")]
    colored: bool,
}

impl Log4rBuilder {
    /// 创建新的 Builder，使用默认配置
    ///
    /// 默认配置：级别 INFO，stdout 控制台，异步启用，队列大小 10000。
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::Log4rBuilder;
    ///
    /// let builder = Log4rBuilder::new();
    /// ```
    pub fn new() -> Self {
        Self {
            level: Level::Info,
            app_name: None,
            console_target: Some(ConsoleTarget::Stdout),
            file_path: None,
            rotation_size: None,
            rotation_period: RotationPeriod::None,
            max_files: None,
            async_enabled: true,
            queue_size: 10000,
            batch_size: 100,
            batch_timeout_ms: 100,
            #[cfg(feature = "color")]
            colored: false,
        }
    }

    /// 设置全局日志级别
    ///
    /// # Arguments
    ///
    /// * `level` - 日志级别，低于此级别的日志将被过滤
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::{Log4rBuilder, Level};
    ///
    /// let builder = Log4rBuilder::new().with_level(Level::Debug);
    /// ```
    pub fn with_level(mut self, level: Level) -> Self {
        self.level = level;
        self
    }

    /// 设置应用名称
    ///
    /// 应用名称用于系统日志标识和日志输出。
    ///
    /// # Arguments
    ///
    /// * `name` - 应用名称，支持 `&str`、`String` 等类型
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::Log4rBuilder;
    ///
    /// let builder = Log4rBuilder::new().with_app_name("my-app");
    /// ```
    pub fn with_app_name(mut self, name: impl Into<String>) -> Self {
        self.app_name = Some(name.into());
        self
    }

    /// 配置控制台输出目标
    ///
    /// # Arguments
    ///
    /// * `target` - 控制台输出目标，`Stdout` 或 `Stderr`
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::{Log4rBuilder, ConsoleTarget};
    ///
    /// let builder = Log4rBuilder::new().with_console(ConsoleTarget::Stderr);
    /// ```
    pub fn with_console(mut self, target: ConsoleTarget) -> Self {
        self.console_target = Some(target);
        self
    }

    /// 配置文件输出路径
    ///
    /// 如果目录不存在，将自动创建。
    ///
    /// # Arguments
    ///
    /// * `path` - 日志文件路径，支持相对路径和绝对路径
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::Log4rBuilder;
    ///
    /// let builder = Log4rBuilder::new().with_file("logs/app.log");
    /// ```
    pub fn with_file(mut self, path: impl AsRef<Path>) -> Self {
        self.file_path = Some(path.as_ref().to_path_buf());
        self
    }

    /// 设置文件轮转大小
    ///
    /// 当日志文件达到指定大小时自动轮转。需要先调用 `with_file()` 设置文件路径。
    ///
    /// # Arguments
    ///
    /// * `size` - 大小字符串，支持 B, KB, MB, GB 单位（大小写不敏感）
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::Log4rBuilder;
    ///
    /// let builder = Log4rBuilder::new()
    ///     .with_file("logs/app.log")
    ///     .with_rotation("10MB");
    /// ```
    pub fn with_rotation(mut self, size: &str) -> Self {
        // 解析大小字符串，失败时使用默认值 10MB
        self.rotation_size = config::parse_size(size).ok();
        self
    }

    /// 设置时间轮转周期
    ///
    /// 按时间周期自动轮转日志文件。可与 `with_rotation()` 同时使用实现双触发。
    ///
    /// # Arguments
    ///
    /// * `period` - 时间轮转周期：`Hourly`、`Daily`、`Weekly` 或 `None`
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::{Log4rBuilder, RotationPeriod};
    ///
    /// // 仅时间轮转
    /// let builder = Log4rBuilder::new()
    ///     .with_file("logs/app.log")
    ///     .with_time_rotation(RotationPeriod::Daily);
    ///
    /// // 时间+大小双触发
    /// let builder = Log4rBuilder::new()
    ///     .with_file("logs/app.log")
    ///     .with_rotation("10MB")
    ///     .with_time_rotation(RotationPeriod::Daily);
    /// ```
    pub fn with_time_rotation(mut self, period: RotationPeriod) -> Self {
        self.rotation_period = period;
        self
    }

    /// 设置历史文件数量限制
    ///
    /// 限制保留的轮转文件数量，超出限制时删除最旧的文件。
    ///
    /// # Arguments
    ///
    /// * `max_files` - 历史文件数量限制，0 表示禁用清理（无限保留）
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::{Log4rBuilder, RotationPeriod};
    ///
    /// // 保留最近 7 个轮转文件
    /// let builder = Log4rBuilder::new()
    ///     .with_file("logs/app.log")
    ///     .with_time_rotation(RotationPeriod::Daily)
    ///     .with_max_files(7);
    ///
    /// // 禁用清理（无限保留）
    /// let builder = Log4rBuilder::new()
    ///     .with_file("logs/app.log")
    ///     .with_rotation("10MB")
    ///     .with_max_files(0);
    /// ```
    pub fn with_max_files(mut self, max_files: u32) -> Self {
        self.max_files = Some(max_files);
        self
    }

    /// 启用或禁用异步模式
    ///
    /// 异步模式下，日志写入在后台线程执行，不阻塞主线程。
    ///
    /// # Arguments
    ///
    /// * `enabled` - `true` 启用异步，`false` 禁用
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::Log4rBuilder;
    ///
    /// // 禁用异步模式
    /// let builder = Log4rBuilder::new().with_async(false);
    /// ```
    pub fn with_async(mut self, enabled: bool) -> Self {
        self.async_enabled = enabled;
        self
    }

    /// 设置异步队列大小
    ///
    /// 队列大小决定了异步模式下可缓冲的日志数量。
    ///
    /// # Arguments
    ///
    /// * `size` - 队列大小，必须大于 0
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::Log4rBuilder;
    ///
    /// let builder = Log4rBuilder::new().with_queue_size(5000);
    /// ```
    pub fn with_queue_size(mut self, size: usize) -> Self {
        self.queue_size = size;
        self
    }

    /// 设置批量处理大小
    ///
    /// 批量大小决定了累积多少条日志后触发批量写入。
    ///
    /// # Arguments
    ///
    /// * `size` - 批量大小，必须大于 0
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::Log4rBuilder;
    ///
    /// let builder = Log4rBuilder::new().with_batch_size(50);
    /// ```
    pub fn with_batch_size(mut self, size: usize) -> Self {
        self.batch_size = size;
        self
    }

    /// 设置批量超时时间（毫秒）
    ///
    /// 超时时间决定了距上次写入多久后强制刷新批次。
    ///
    /// # Arguments
    ///
    /// * `ms` - 超时时间（毫秒），必须大于 0
    ///
    /// # Examples
    ///
    /// ```rust
    /// use log4r::Log4rBuilder;
    ///
    /// let builder = Log4rBuilder::new().with_batch_timeout(200);
    /// ```
    pub fn with_batch_timeout(mut self, ms: u64) -> Self {
        self.batch_timeout_ms = ms;
        self
    }

    /// 启用彩色控制台输出
    ///
    /// 使用 ANSI 颜色代码为不同日志级别显示不同颜色：
    /// - TRACE: 灰色
    /// - DEBUG: 蓝色
    /// - INFO: 绿色
    /// - WARN: 黄色
    /// - ERROR: 红色
    /// - FATAL: 亮红色 + 粗体
    ///
    /// 需要启用 `color` feature。
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use log4r::{builder, ConsoleTarget};
    ///
    /// builder()
    ///     .with_console(ConsoleTarget::Stdout)
    ///     .with_colored()
    ///     .init()?;
    /// ```
    #[cfg(feature = "color")]
    pub fn with_colored(mut self) -> Self {
        self.colored = true;
        self
    }

    /// 配置控制台彩色输出开关
    ///
    /// 允许显式启用或禁用彩色输出。与 `with_colored()` 不同，
    /// 此方法可以显式禁用彩色输出。
    ///
    /// 需要启用 `color` feature。
    ///
    /// # Arguments
    ///
    /// * `enabled` - `true` 启用彩色，`false` 禁用彩色
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use log4r::{builder, ConsoleTarget};
    ///
    /// // 显式禁用彩色输出
    /// builder()
    ///     .with_console(ConsoleTarget::Stdout)
    ///     .with_console_colored(false)
    ///     .init()?;
    /// ```
    #[cfg(feature = "color")]
    pub fn with_console_colored(mut self, enabled: bool) -> Self {
        self.colored = enabled;
        self
    }

    /// 构建并初始化日志系统
    ///
    /// 使用 Builder 配置的选项初始化日志系统。未设置的选项使用合理的默认值：
    /// - 级别：INFO
    /// - 控制台：stdout
    /// - 异步：启用
    /// - 队列大小：10000
    ///
    /// # Errors
    ///
    /// - [`Log4rError::AlreadyInitialized`] - 日志系统已初始化
    /// - [`Log4rError::ConfigError`] - 配置无效
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// use log4r::{builder, Level, ConsoleTarget};
    ///
    /// // 使用默认配置
    /// builder().init()?;
    ///
    /// // 自定义配置
    /// builder()
    ///     .with_level(Level::Debug)
    ///     .with_console(ConsoleTarget::Stderr)
    ///     .with_file("logs/app.log")
    ///     .init()?;
    /// ```
    pub fn init(self) -> Result<(), Log4rError> {
        // 检查是否已初始化
        if INITIALIZED.swap(true, Ordering::SeqCst) {
            return Err(Log4rError::AlreadyInitialized);
        }

        // 直接创建 Appender 列表（支持彩色输出）
        let mut appenders: Vec<Arc<dyn Appender>> = Vec::new();

        // 创建控制台 Appender
        if let Some(target) = self.console_target {
            #[cfg(feature = "color")]
            let console: Arc<dyn Appender> = if self.colored {
                Arc::new(
                    ConsoleAppender::with_target(target)
                        .with_level(self.level)
                        .with_colored(),
                )
            } else {
                Arc::new(ConsoleAppender::with_target(target).with_level(self.level))
            };

            #[cfg(not(feature = "color"))]
            let console: Arc<dyn Appender> =
                Arc::new(ConsoleAppender::with_target(target).with_level(self.level));

            appenders.push(console);
        }

        // 创建文件 Appender（根据 rotation_size 和 rotation_period 选择类型）
        if let Some(ref path) = self.file_path {
            // 如果启用了大小轮转或时间轮转，使用 RotatingFileAppender
            if self.rotation_size.is_some() || self.rotation_period != RotationPeriod::None {
                let rotating_appender = appender::RotatingFileAppender::with_full_config(
                    path,
                    self.rotation_size,
                    self.rotation_period,
                    self.max_files,
                )
                .inspect_err(|_| {
                    INITIALIZED.store(false, Ordering::SeqCst);
                })?
                .with_level(self.level);
                appenders.push(Arc::new(rotating_appender));
            } else {
                // 使用普通 FileAppender
                let file_appender = appender::FileAppender::new(path)
                    .inspect_err(|_| {
                        INITIALIZED.store(false, Ordering::SeqCst);
                    })?
                    .with_level(self.level);
                appenders.push(Arc::new(file_appender));
            }
        }

        // 构建配置（用于存储）
        let config = config::Log4rConfig {
            level: self.level,
            app_name: self.app_name.clone().unwrap_or_else(|| "log4r".to_string()),
            modules: std::collections::HashMap::new(),
            appenders: config::AppendersConfig {
                console: None,
                file: None,
            },
            format: config::FormatConfig::default(),
            async_config: config::AsyncConfig {
                enabled: self.async_enabled,
                queue_size: self.queue_size,
                backpressure: config::BackpressureStrategy::default(),
                batch_size: self.batch_size,
                batch_timeout_ms: self.batch_timeout_ms,
            },
        };

        // 验证异步配置
        if let Err(e) = config.async_config.validate() {
            INITIALIZED.store(false, Ordering::SeqCst);
            return Err(e);
        }

        // 创建异步通道和 Worker
        let channel = LogChannel::new(self.queue_size);
        let sender = channel.sender();
        let receiver = channel.receiver().clone();

        // 创建 fallback Appender（stderr）并启动 Worker
        let fallback: Arc<dyn Appender> =
            Arc::new(ConsoleAppender::with_target(ConsoleTarget::Stderr));
        let app_name = self.app_name.unwrap_or_else(|| "log4r".to_string());
        // AC-14.4.5 #9: 从 Builder 字段构建 WorkerConfig
        let worker_config = WorkerConfig {
            batch_size: self.batch_size,
            batch_timeout_ms: self.batch_timeout_ms,
        };
        let worker = Worker::start(
            receiver,
            appenders.clone(),
            fallback,
            worker_config,
            app_name,
        );

        // 创建 Log4rLayer 并注册到 tracing
        let layer = Log4rLayer::new(sender.clone(), self.level);
        let subscriber = tracing_subscriber::registry().with(layer);

        if let Err(e) = tracing::subscriber::set_global_default(subscriber) {
            INITIALIZED.store(false, Ordering::SeqCst);
            return Err(Log4rError::ConfigError(format!(
                "设置 subscriber 失败: {}",
                e
            )));
        }

        // 注册 panic hook
        register_panic_hook();

        // 存储 GlobalLogger
        let logger = GlobalLogger {
            config,
            appenders,
            worker: Some(worker),
            sender: Some(sender),
            fallback: ConsoleAppender::with_target(ConsoleTarget::Stderr),
        };

        if LOGGER.set(Mutex::new(logger)).is_err() {
            INITIALIZED.store(false, Ordering::SeqCst);
            return Err(Log4rError::AlreadyInitialized);
        }

        Ok(())
    }
}

impl Default for Log4rBuilder {
    fn default() -> Self {
        Self::new()
    }
}

/// 重置全局日志状态（仅测试用）
///
/// 此函数仅在测试时可用，用于重置全局日志状态以实现测试隔离。
///
/// # 注意
///
/// 此函数为内部测试 API，不保证稳定性。
#[cfg(test)]
pub fn __test_reset() {
    // 重置 INITIALIZED 标志
    INITIALIZED.store(false, Ordering::SeqCst);
    // 重置 SHUTDOWN_CALLED 标志
    SHUTDOWN_CALLED.store(false, Ordering::SeqCst);
    // 重置内部错误计数器
    INTERNAL_ERROR_COUNT.store(0, Ordering::SeqCst);
    // 注意：OnceLock 和 PANIC_HOOK_REGISTERED 无法重置，测试需要在独立进程中运行
}

/// 重置全局日志状态（仅测试用，供集成测试调用）
///
/// 此函数仅在测试时可用，用于重置全局日志状态以实现测试隔离。
#[doc(hidden)]
pub fn __test_reset_for_integration() {
    // 重置 INITIALIZED 标志
    INITIALIZED.store(false, Ordering::SeqCst);
    // 重置 SHUTDOWN_CALLED 标志
    SHUTDOWN_CALLED.store(false, Ordering::SeqCst);
    // 重置内部错误计数器
    INTERNAL_ERROR_COUNT.store(0, Ordering::SeqCst);
    // 注意：OnceLock 和 PANIC_HOOK_REGISTERED 无法重置，测试需要在独立进程中运行
}

#[cfg(test)]
mod tests {
    use super::*;

    // UT-LIB-001: 测试 __test_reset 函数不会 panic
    #[test]
    fn test_reset_does_not_panic() {
        // GIVEN/WHEN: 调用 __test_reset
        __test_reset();

        // THEN: 不应 panic
    }

    // UT-LIB-002: 测试 __test_reset 可多次调用
    #[test]
    fn test_reset_can_be_called_multiple_times() {
        // GIVEN/WHEN: 多次调用 __test_reset
        for _ in 0..10 {
            __test_reset();
        }

        // THEN: 不应 panic
    }

    // UT-LIB-003: 测试公共导出类型可用
    #[test]
    fn test_public_exports_available() {
        // GIVEN/WHEN: 使用公共导出的类型
        let _level = Level::Info;
        let _event = LogEvent::new(Level::Info, "test", "message");
        let _formatter = TextFormatter::new();
        let _appender = ConsoleAppender::new();

        // THEN: 编译通过即验证成功
    }

    // UT-LIB-004: 测试 Log4rError 可用
    #[test]
    fn test_error_type_available() {
        // GIVEN/WHEN: 创建错误类型
        let err = Log4rError::config("测试错误");

        // THEN: 应正确创建
        assert!(err.to_string().contains("测试错误"));
    }

    // UT-LIB-005: 测试 ParseLevelError 可用
    #[test]
    fn test_parse_level_error_available() {
        // GIVEN/WHEN: 解析无效级别
        let result: Result<Level, ParseLevelError> = "invalid".parse();

        // THEN: 应返回错误
        assert!(result.is_err());
    }

    // UT-7.1-001: 测试 is_initialized() 初始为 false
    #[test]
    fn test_is_initialized_initial_false() {
        // GIVEN: 重置状态
        __test_reset();

        // WHEN: 检查初始化状态
        // THEN: 应为 false
        // 注意：由于全局状态，此测试可能受其他测试影响
        // 在实际测试中应使用 serial_test
    }

    // UT-7.1-002: 测试 Log4rBuilder 默认值
    #[test]
    fn test_builder_defaults() {
        // GIVEN/WHEN: 创建默认 Builder
        let builder = Log4rBuilder::new();

        // THEN: 默认值应正确
        assert_eq!(builder.level, Level::Info);
        assert!(builder.app_name.is_none());
        assert_eq!(builder.console_target, Some(ConsoleTarget::Stdout));
        assert!(builder.file_path.is_none());
        assert!(builder.async_enabled);
        assert_eq!(builder.queue_size, 10000);
    }

    // UT-7.1-003: 测试 Log4rBuilder 链式调用
    #[test]
    fn test_builder_chain() {
        // GIVEN/WHEN: 链式调用 Builder 方法
        let builder = Log4rBuilder::new()
            .with_level(Level::Debug)
            .with_app_name("test_app")
            .with_console(ConsoleTarget::Stderr)
            .with_async(false)
            .with_queue_size(5000);

        // THEN: 所有值应正确设置
        assert_eq!(builder.level, Level::Debug);
        assert_eq!(builder.app_name, Some("test_app".to_string()));
        assert_eq!(builder.console_target, Some(ConsoleTarget::Stderr));
        assert!(!builder.async_enabled);
        assert_eq!(builder.queue_size, 5000);
    }

    // UT-7.1-004: 测试 GlobalLogger 结构体字段
    #[test]
    fn test_global_logger_fields() {
        // GIVEN: 创建 GlobalLogger 所需的组件
        let config = config::Log4rConfig::default();
        let appenders: Vec<Arc<dyn Appender>> = vec![];
        let fallback = ConsoleAppender::with_target(ConsoleTarget::Stderr);

        // WHEN: 创建 GlobalLogger
        let logger = GlobalLogger {
            config,
            appenders,
            worker: None,
            sender: None,
            fallback,
        };

        // THEN: 应成功创建
        assert!(logger.worker.is_none());
        assert!(logger.sender.is_none());
    }

    // =========================================================================
    // Story 7.3: Builder 模式初始化单元测试
    // =========================================================================

    // UT-7.3-001: 测试 Log4rBuilder::new() 默认值正确 (AC-7.3.3)
    #[test]
    fn test_builder_new_defaults() {
        // GIVEN/WHEN: 创建新的 Builder
        let builder = Log4rBuilder::new();

        // THEN: 默认值应符合 AC-7.3.3（级别 INFO，stdout 控制台，异步启用）
        assert_eq!(builder.level, Level::Info, "默认级别应为 INFO");
        assert_eq!(
            builder.console_target,
            Some(ConsoleTarget::Stdout),
            "默认控制台应为 stdout"
        );
        assert!(builder.async_enabled, "默认应启用异步");
        assert_eq!(builder.queue_size, 10000, "默认队列大小应为 10000");
    }

    // UT-7.3-002: 测试 with_level() 设置级别 (AC-7.3.1)
    #[test]
    fn test_builder_with_level() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 设置级别为 Debug
        let builder = builder.with_level(Level::Debug);

        // THEN: 级别应为 Debug
        assert_eq!(builder.level, Level::Debug);
    }

    // UT-7.3-003: 测试 with_app_name() 设置应用名 (AC-7.3.1)
    #[test]
    fn test_builder_with_app_name() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 设置应用名
        let builder = builder.with_app_name("my-test-app");

        // THEN: 应用名应正确设置
        assert_eq!(builder.app_name, Some("my-test-app".to_string()));
    }

    // UT-7.3-004: 测试 with_console() 设置控制台目标 (AC-7.3.1)
    #[test]
    fn test_builder_with_console() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 设置控制台为 stderr
        let builder = builder.with_console(ConsoleTarget::Stderr);

        // THEN: 控制台目标应为 stderr
        assert_eq!(builder.console_target, Some(ConsoleTarget::Stderr));
    }

    // UT-7.3-005: 测试 with_file() 设置文件路径 (AC-7.3.1)
    #[test]
    fn test_builder_with_file() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 设置文件路径
        let builder = builder.with_file("logs/app.log");

        // THEN: 文件路径应正确设置
        assert_eq!(
            builder.file_path,
            Some(std::path::PathBuf::from("logs/app.log"))
        );
    }

    // UT-7.3-006: 测试 with_async() 设置异步模式 (AC-7.3.1)
    #[test]
    fn test_builder_with_async() {
        // GIVEN: 新的 Builder（默认异步启用）
        let builder = Log4rBuilder::new();
        assert!(builder.async_enabled);

        // WHEN: 禁用异步
        let builder = builder.with_async(false);

        // THEN: 异步应被禁用
        assert!(!builder.async_enabled);
    }

    // UT-7.3-007: 测试 with_queue_size() 设置队列大小 (AC-7.3.1)
    #[test]
    fn test_builder_with_queue_size() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 设置队列大小
        let builder = builder.with_queue_size(5000);

        // THEN: 队列大小应正确设置
        assert_eq!(builder.queue_size, 5000);
    }

    // UT-7.3-008: 测试链式调用设置多个选项 (AC-7.3.1)
    #[test]
    fn test_builder_chain_all_options() {
        // GIVEN/WHEN: 链式调用设置所有选项
        let builder = Log4rBuilder::new()
            .with_level(Level::Warn)
            .with_app_name("chain-test")
            .with_console(ConsoleTarget::Stderr)
            .with_file("logs/chain.log")
            .with_async(false)
            .with_queue_size(2000);

        // THEN: 所有选项应正确设置
        assert_eq!(builder.level, Level::Warn);
        assert_eq!(builder.app_name, Some("chain-test".to_string()));
        assert_eq!(builder.console_target, Some(ConsoleTarget::Stderr));
        assert_eq!(
            builder.file_path,
            Some(std::path::PathBuf::from("logs/chain.log"))
        );
        assert!(!builder.async_enabled);
        assert_eq!(builder.queue_size, 2000);
    }

    // UT-7.3-009: 测试 Default trait 实现 (AC-7.3.3)
    #[test]
    fn test_builder_default_trait() {
        // GIVEN/WHEN: 使用 Default trait 创建 Builder
        let builder = Log4rBuilder::default();

        // THEN: 应与 new() 相同
        let new_builder = Log4rBuilder::new();
        assert_eq!(builder.level, new_builder.level);
        assert_eq!(builder.app_name, new_builder.app_name);
        assert_eq!(builder.console_target, new_builder.console_target);
        assert_eq!(builder.file_path, new_builder.file_path);
        assert_eq!(builder.async_enabled, new_builder.async_enabled);
        assert_eq!(builder.queue_size, new_builder.queue_size);
    }

    // UT-7.3-010: 测试 builder() 函数返回 Log4rBuilder (AC-7.3.1)
    #[test]
    fn test_builder_function() {
        // GIVEN/WHEN: 调用 builder() 函数
        let builder = builder();

        // THEN: 应返回默认配置的 Builder
        assert_eq!(builder.level, Level::Info);
        assert_eq!(builder.console_target, Some(ConsoleTarget::Stdout));
    }

    // UT-7.3-011: 测试 with_app_name 接受 String 类型 (AC-7.3.1)
    #[test]
    fn test_builder_with_app_name_string() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 使用 String 类型设置应用名
        let name = String::from("string-app");
        let builder = builder.with_app_name(name);

        // THEN: 应用名应正确设置
        assert_eq!(builder.app_name, Some("string-app".to_string()));
    }

    // UT-7.3-012: 测试 with_file 接受 PathBuf 类型 (AC-7.3.1)
    #[test]
    fn test_builder_with_file_pathbuf() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 使用 PathBuf 类型设置文件路径
        let path = std::path::PathBuf::from("logs/pathbuf.log");
        let builder = builder.with_file(&path);

        // THEN: 文件路径应正确设置
        assert_eq!(builder.file_path, Some(path));
    }

    // UT-7.3-013: 测试 Log4rBuilder 实现 Debug trait
    #[test]
    fn test_builder_debug() {
        // GIVEN: 创建 Builder
        let builder = Log4rBuilder::new().with_level(Level::Debug);

        // WHEN: 格式化为 Debug 字符串
        let debug_str = format!("{:?}", builder);

        // THEN: 应包含字段信息
        assert!(debug_str.contains("Log4rBuilder"));
        assert!(debug_str.contains("Debug"));
    }

    // UT-7.3-014: 测试 Log4rBuilder 实现 Clone trait
    #[test]
    fn test_builder_clone() {
        // GIVEN: 创建配置好的 Builder
        let builder = Log4rBuilder::new()
            .with_level(Level::Warn)
            .with_app_name("clone-test");

        // WHEN: 克隆 Builder
        let cloned = builder.clone();

        // THEN: 克隆应与原始相同
        assert_eq!(cloned.level, Level::Warn);
        assert_eq!(cloned.app_name, Some("clone-test".to_string()));
    }

    // UT-7.3-015: 测试所有日志级别可通过 with_level 设置 (AC-7.3.1)
    #[test]
    fn test_builder_all_levels() {
        // 测试所有级别
        let levels = [
            Level::Trace,
            Level::Debug,
            Level::Info,
            Level::Warn,
            Level::Error,
            Level::Fatal,
        ];

        for level in levels {
            let builder = Log4rBuilder::new().with_level(level);
            assert_eq!(builder.level, level, "级别 {:?} 应正确设置", level);
        }
    }

    // =========================================================================
    // Story 7.5: 进程退出自动 flush 单元测试
    // =========================================================================

    // UT-7.5-001: 测试 GlobalLogger Drop 实现存在且不 panic (AC-7.5.3)
    #[test]
    fn test_global_logger_drop_does_not_panic() {
        // GIVEN: 创建 GlobalLogger（无 Worker）
        let config = config::Log4rConfig::default();
        let appenders: Vec<Arc<dyn Appender>> = vec![];
        let fallback = ConsoleAppender::with_target(ConsoleTarget::Stderr);

        let logger = GlobalLogger {
            config,
            appenders,
            worker: None,
            sender: None,
            fallback,
        };

        // WHEN: Drop GlobalLogger
        drop(logger);

        // THEN: 不应 panic（测试通过即验证）
    }

    // UT-7.5-002: 测试 SHUTDOWN_CALLED 标志防止重复 flush (AC-7.5.4)
    #[test]
    fn test_shutdown_called_flag_prevents_duplicate_flush() {
        // GIVEN: 重置状态
        __test_reset();

        // WHEN: 设置 SHUTDOWN_CALLED 为 true
        SHUTDOWN_CALLED.store(true, Ordering::SeqCst);

        // 创建 GlobalLogger
        let config = config::Log4rConfig::default();
        let appenders: Vec<Arc<dyn Appender>> = vec![];
        let fallback = ConsoleAppender::with_target(ConsoleTarget::Stderr);

        let logger = GlobalLogger {
            config,
            appenders,
            worker: None,
            sender: None,
            fallback,
        };

        // THEN: Drop 时应跳过 flush（因为 SHUTDOWN_CALLED 已为 true）
        drop(logger);

        // 验证标志仍为 true
        assert!(SHUTDOWN_CALLED.load(Ordering::SeqCst));

        // 清理
        __test_reset();
    }

    // UT-7.5-003: 测试 register_panic_hook 可多次调用不 panic (AC-7.5.2)
    #[test]
    fn test_register_panic_hook_idempotent() {
        // GIVEN/WHEN: 多次调用 register_panic_hook
        register_panic_hook();
        register_panic_hook();
        register_panic_hook();

        // THEN: 不应 panic（测试通过即验证）
        // 注意：PANIC_HOOK_REGISTERED 无法重置，但多次调用应安全
    }

    // UT-7.5-004: 测试 shutdown() 后 SHUTDOWN_CALLED 为 true (AC-7.5.4)
    #[test]
    fn test_shutdown_sets_shutdown_called_flag() {
        // GIVEN: 重置状态
        __test_reset();
        INITIALIZED.store(true, Ordering::SeqCst);

        // WHEN: 调用 shutdown（会因为 LOGGER 未设置而跳过实际关闭）
        // 但 SHUTDOWN_CALLED 应被设置
        let _ = shutdown();

        // THEN: SHUTDOWN_CALLED 应为 true
        assert!(SHUTDOWN_CALLED.load(Ordering::SeqCst));

        // 清理
        __test_reset();
    }

    // UT-7.5-005: 测试重复调用 shutdown 返回 Ok (AC-7.5.4)
    #[test]
    fn test_shutdown_idempotent() {
        // GIVEN: 重置状态并设置已初始化
        __test_reset();
        INITIALIZED.store(true, Ordering::SeqCst);

        // WHEN: 第一次调用 shutdown
        let result1 = shutdown();

        // THEN: 应成功（或因 LOGGER 未设置而成功）
        assert!(result1.is_ok());

        // WHEN: 第二次调用 shutdown
        let result2 = shutdown();

        // THEN: 应返回 Ok（因为 SHUTDOWN_CALLED 已为 true）
        assert!(result2.is_ok());

        // 清理
        __test_reset();
    }

    // UT-7.5-006: 测试 GlobalLogger Drop 设置 SHUTDOWN_CALLED (AC-7.5.4)
    #[test]
    fn test_global_logger_drop_sets_shutdown_called() {
        // GIVEN: 重置状态
        __test_reset();
        assert!(!SHUTDOWN_CALLED.load(Ordering::SeqCst));

        // 创建 GlobalLogger
        let config = config::Log4rConfig::default();
        let appenders: Vec<Arc<dyn Appender>> = vec![];
        let fallback = ConsoleAppender::with_target(ConsoleTarget::Stderr);

        let logger = GlobalLogger {
            config,
            appenders,
            worker: None,
            sender: None,
            fallback,
        };

        // WHEN: Drop GlobalLogger
        drop(logger);

        // THEN: SHUTDOWN_CALLED 应为 true
        assert!(SHUTDOWN_CALLED.load(Ordering::SeqCst));

        // 清理
        __test_reset();
    }

    // UT-7.5-007: 测试 __test_reset 重置 SHUTDOWN_CALLED (AC-7.5.4)
    #[test]
    fn test_reset_clears_shutdown_called() {
        // GIVEN: 设置 SHUTDOWN_CALLED 为 true
        SHUTDOWN_CALLED.store(true, Ordering::SeqCst);

        // WHEN: 调用 __test_reset
        __test_reset();

        // THEN: SHUTDOWN_CALLED 应为 false
        assert!(!SHUTDOWN_CALLED.load(Ordering::SeqCst));
    }

    // UT-7.5-008: 测试 PANIC_HOOK_REGISTERED 初始为 false
    #[test]
    fn test_panic_hook_registered_exists() {
        // GIVEN/WHEN: 检查 PANIC_HOOK_REGISTERED 存在
        // THEN: 应能读取（不 panic）
        let _ = PANIC_HOOK_REGISTERED.load(Ordering::SeqCst);
    }

    // =========================================================================
    // Story 7.6: 错误隔离和降级单元测试
    // =========================================================================

    // UT-7.6-007: 测试 log_internal_error() 函数存在且可调用 (AC-7.6.3)
    #[test]
    fn test_log_internal_error_callable() {
        // GIVEN/WHEN: 调用 log_internal_error
        log_internal_error("测试消息");

        // THEN: 不应 panic（测试通过即验证）
    }

    // UT-7.6-008: 测试 INTERNAL_ERROR_COUNT 计数器存在 (AC-7.6.3)
    #[test]
    fn test_internal_error_count_exists() {
        // GIVEN/WHEN: 读取计数器
        let _count = INTERNAL_ERROR_COUNT.load(Ordering::SeqCst);

        // THEN: 应能读取（不 panic，测试通过即验证）
    }

    // UT-7.6-009: 测试 __test_reset 重置 INTERNAL_ERROR_COUNT (AC-7.6.3)
    #[test]
    fn test_reset_clears_internal_error_count() {
        // GIVEN: 设置错误计数器为非零值
        INTERNAL_ERROR_COUNT.store(999, Ordering::SeqCst);

        // WHEN: 调用 __test_reset
        __test_reset();

        // THEN: 计数器应为 0
        assert_eq!(INTERNAL_ERROR_COUNT.load(Ordering::SeqCst), 0);
    }

    // UT-7.6-010: 测试 log_internal_error 不会 panic (AC-7.6.3)
    #[test]
    fn test_log_internal_error_no_panic() {
        // GIVEN/WHEN: 调用 log_internal_error 多次（包括边界情况）
        log_internal_error("");
        log_internal_error("普通消息");
        log_internal_error("包含特殊字符: \n\t\r");
        log_internal_error(&"很长的消息".repeat(100));

        // THEN: 不应 panic（测试通过即验证）
    }

    // =========================================================================
    // Story 14.4: Builder 批量配置测试
    // =========================================================================

    // UT-14.4-B01: 测试 Log4rBuilder 默认 batch_size = 100 (AC-14.4.3)
    #[test]
    fn test_builder_default_batch_size() {
        // GIVEN/WHEN: 创建默认 Builder
        let builder = Log4rBuilder::new();

        // THEN: batch_size 应为 100
        assert_eq!(builder.batch_size, 100);
    }

    // UT-14.4-B02: 测试 Log4rBuilder 默认 batch_timeout_ms = 100 (AC-14.4.3)
    #[test]
    fn test_builder_default_batch_timeout_ms() {
        // GIVEN/WHEN: 创建默认 Builder
        let builder = Log4rBuilder::new();

        // THEN: batch_timeout_ms 应为 100
        assert_eq!(builder.batch_timeout_ms, 100);
    }

    // UT-14.4-B03: 测试 with_batch_size() 设置批量大小 (AC-14.4.3 #5)
    #[test]
    fn test_builder_with_batch_size() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 设置 batch_size 为 50
        let builder = builder.with_batch_size(50);

        // THEN: batch_size 应为 50
        assert_eq!(builder.batch_size, 50);
    }

    // UT-14.4-B04: 测试 with_batch_timeout() 设置超时时间 (AC-14.4.3 #6)
    #[test]
    fn test_builder_with_batch_timeout() {
        // GIVEN: 新的 Builder
        let builder = Log4rBuilder::new();

        // WHEN: 设置 batch_timeout_ms 为 200
        let builder = builder.with_batch_timeout(200);

        // THEN: batch_timeout_ms 应为 200
        assert_eq!(builder.batch_timeout_ms, 200);
    }

    // UT-14.4-B05: 测试 Builder 链式调用批量配置 (AC-14.4.3)
    #[test]
    fn test_builder_chain_batch_config() {
        // GIVEN/WHEN: 链式调用设置批量参数
        let builder = Log4rBuilder::new()
            .with_batch_size(50)
            .with_batch_timeout(200);

        // THEN: 所有值应正确设置
        assert_eq!(builder.batch_size, 50);
        assert_eq!(builder.batch_timeout_ms, 200);
    }

    // UT-14.4-B06: 测试 Builder 批量配置与其他配置组合 (AC-14.4.3)
    #[test]
    fn test_builder_batch_config_with_other_options() {
        // GIVEN/WHEN: 组合多种配置
        let builder = Log4rBuilder::new()
            .with_level(Level::Debug)
            .with_queue_size(5000)
            .with_batch_size(50)
            .with_batch_timeout(200);

        // THEN: 所有值应正确设置
        assert_eq!(builder.level, Level::Debug);
        assert_eq!(builder.queue_size, 5000);
        assert_eq!(builder.batch_size, 50);
        assert_eq!(builder.batch_timeout_ms, 200);
    }
}
